Tighten NameSchema to hyphen-only 2–64 and migrate legacy ./_ names - #536

Summary

Align TrueForge shared NameSchema (ResourceName) with ServiceFoundry agent-identity / RemoteAgentV2: hyphen-only, 2–64 (^[a-z][a-z0-9-]{0,62}[a-z0-9]$).

One schema for local resource names (agents, skills, MCP servers, models, schedules). Postgres + SQLite migration rewrites legacy local names that used . / _.

Closes AGE-2065

Why

• TF agent names must match SVC PUT /internal/tfg/agents / agent-identity (source=trueforge).
• Older TF ResourceName allowed . / _; that breaks SVC sync and diverges from RemoteAgentV2.
• Prefer one shared NameSchema over a separate AgentNameSchema so standalone create/list/update stay consistent after migrate.

Changes

Schema

• Tighten NameSchema in packages/trueforge/src/schemas/common.ts to hyphen-only 2–64.
• OpenAPI name remains ResourceName (CI regenerates OpenAPI + SDK; no hand-edits).
• Document TFY vs standalone vs migration behavior on NameSchema.

API / validation impact

• Create/update APIs that use NameSchema reject names with . or _ (e.g. my.agent, my_agent).
• Reserved agent names (tfg, trueforge) unchanged.
• AgentSpec refs (model / skills / MCP) stay plain strings — FQNs and long SVC names still allowed in manifests.

TrueFoundry mode

• Agents: created/synced under NameSchema (must satisfy SVC identity).
• Skills / MCP / models: fetched from SVC; not NameSchema-checked on those paths (FQNs / longer SVC MCP names OK).
• Schedules: still local; use NameSchema.

Standalone mode

• Agents, skills, MCP, models, schedules are created locally under the same NameSchema.

Migration (20260911_000001_name_hyphen_only)

• Shared planner: planHyphenOnlyRenames.ts
• Shared apply: applyNameHyphenOnlyMigration.ts
• Wired for Postgres and SQLite
• Rewrites only strings matching legacy NameSchema that fail the new rule (contain . / _)
• Replace . / _ → -, always append -<4 hex>; truncate to ≤ 64
• Leaves alone: already hyphen-only names, FQNs, other non-matching strings
• Updates:
  • agent.name + denorm session.agent_name / schedule.agent_name
  • skill.name
  • mcp_server.name (+ manifest.name)
  • model_provider.name (+ nested models[].name, custom manifest.name)
  • schedule.name
  • AgentSpec refs on agent/session manifests
• Irreversible (down throws); originals not retained; no occupancy / collision check on suffix

Tests

• nameSchema.test.ts — accept/reject matrix
• planHyphenOnlyRenames.test.ts — rename + FQN skip + AgentSpec rewrite maps
• agents.test.ts — API rejects my.agent / my_agent
• trueFoundryNaming.test.ts — TFY runtime: agent name still NameSchema; skill FQN / long MCP / model FQN work on create/update, stores, mappers; OpenAPI MCP schemas may still be stricter than runtime (documented)

Release

• Patch changeset for @truefoundry/trueforge
• OpenAPI / @truefoundry/trueforge-sdk regenerate in CI after merge (do not hand-edit)

Out of scope / known skew

• SVC TrueFoundryAgentManifest (3–32, no --) is not the TF ensure path; TF aligns to agent-identity (2–64).
• TFY MCP list/get can return names longer than 64 / outside NameSchema; some OpenAPI MCP types still declare ResourceName — runtime path does not re-parse those schemas today.
• Clients hardcoding old . / _ local names must switch to post-migration names.

How was this tested?

• Unit: nameSchema, planHyphenOnlyRenames, trueFoundryNaming, agents API reject cases
• Full package / root pnpm test (as needed before merge)
• pnpm smoke / migrate against a DB that still has legacy . / _ names (recommended)
• Manual: create agent with hyphen name; reject dotted name; TFY agent with skill FQN + model FQN in manifest

Checklist

• I have read the contributing guidelines
• pnpm build, pnpm test, pnpm typecheck, pnpm lint:ci, and pnpm format:check pass locally
• Tests added/updated where it makes sense
• No hand-edits to generated code (packages/trueforge-sdk, .github/fern/openapi/openapi.json, docs/openapi.json) — fork PRs omit SDK regen; maintainers regenerate after merge
• Docs / .env.example updated if configuration or behavior changed